docs: capture release-please single-root-package lesson#229
Open
theagenticguy wants to merge 2 commits into
Open
docs: capture release-please single-root-package lesson#229theagenticguy wants to merge 2 commits into
theagenticguy wants to merge 2 commits into
Conversation
Document why collapsing to a single root release-please component with a scoped package-name cannot create a release (the `||` coercion derives a component the component-less release PR can't match -> release_created=false -> npm never publishes), and that the fix is two components + the linked-versions plugin so the published CLI bumps on every commit. Indexed in .erpaval/INDEX.md.
…ctional Surfaced by a new erpaval lesson-corpus detector (Bedrock Titan v2 embeddings + structural checks) run over .erpaval/solutions: - 3 orphans (on disk, absent from INDEX.md) now linked at topical anchors: tree-sitter-wasms-catalog-incompat, pnpm-install-on-efs, finch-as-docker-shim. - Release/CI lesson family had asymmetric cross-links: release-published-event and workflow-call-permissions-ceiling had no/partial related: despite three lessons pointing at them. Made the family ring bidirectional (4 files). - Moved release-please-single-root-package out from under the Specs header (this PR had originally appended it there) into the conventions cluster. Detector verdict: 0 merge candidates. Every near-duplicate cluster is an adjacent family where each lesson carries distinct file:line mechanism: the corpus was under-linked, not bloated. Cross-link, never merge.
theagenticguy
force-pushed
the
chore/erpaval-release-lesson
branch
from
c22f4e9 to
fb739dd
Compare
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
What
Captures the durable release-pipeline lesson from this session, and applies the first run of a new ERPAVal lesson-corpus health detector to fix drift the sweep surfaced.
1. The lesson (original scope)
solutions/conventions/release-please-single-root-package-cannot-release.md— why a single root release-please component with a scopedpackage-namecannot create a release in v17 (this.component = options.component || normalizeComponent(packageName)falsy-coerces the empty component → derivescli→buildRelease's standalone check rejects the component-less PR →release_created=false→ npm never publishes), and the fix: two components + thelinked-versionsplugin.2. Detector-driven corpus hygiene (expanded scope)
Built
erpaval-compress.pyinto the erpaval skill (personal-plugins) — embeds the whole lesson corpus (Bedrock Titan v2), then flags orphans, dead links, and semantic-overlap clusters read-only. First run over.erpaval/solutions(55 lessons) found:tree-sitter-wasms-catalog-incompat,pnpm-install-on-efs,finch-as-docker-shim.release-published-event-needs-pat-or-inlinehad norelated:block despite 3 lessons pointing at it;workflow-call-permissions-ceilingwasn't in the family. Made the ring bidirectional across 4 files (using the corpus's existingrelated:+[[slug]]convention).## Specsheader — moved it into the conventions cluster where it belongs.Detector verdict: 0 merge candidates. Every "near-duplicate" cluster is an adjacent family where each lesson carries distinct file:line mechanism. The corpus was under-linked, not bloated — so the fix is navigational (cross-links + index), never a lossy prose merge.
Why
The single-component "fix" cost a multi-attempt recovery and turned out structurally impossible; documenting it so a future session reaches for
linked-versionsdirectly. The detector additions make this kind of drift visible automatically as the corpus grows past ~40 lessons, instead of waiting for a reader to notice the index feels noisy.Verification
related:cross-link targets all resolve to real files.mise run typecheck+mise run testgreen (a stale-dist/typecheck failure after rebasing onto the merged fix(ingestion,cli): make a broken parser fail loud, not silently produce a symbol-free graph #204 was rebuilt away — the documented stale-dist pattern, not a source regression).Docs-only; no code or release-config change.